feat: D2 · Template browser + editor integration - #375

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@resources/js/visual-editor/site-editor/entity-browser.css`:
- Around line 92-107: The CSS uses the keyword currentColor in the
.ap-site-editor__entity-browser-retry rules (border: 1px solid currentColor; and
outline: 2px solid currentColor;) which violates the stylelint keyword-case
rule; update those keyword usages to lowercase (currentcolor) in the
.ap-site-editor__entity-browser-retry block and its :focus-visible rule so the
property values match the configured lowercase keyword expectation.

In `@resources/js/visual-editor/site-editor/entity-browser.tsx`:
- Around line 105-124: The entity list hook isn't resetting pagination when the
active filter chip changes; update useEntityList to either accept a reset signal
or return a setter for its internal page state (e.g., export setPage alongside
items/status/errorMessage/refresh) and then call setPage(1) whenever
activeChipId (or activeChip) changes in entity-browser.tsx; specifically, modify
the useEntityList hook to expose setPage (or a resetPage() method) and invoke
setPage(1) in a useEffect watching activeChipId (or activeChip) after calling
refresh so the list always starts at page 1 for new filters.

In `@resources/js/visual-editor/site-editor/entity-editor-canvas.css`:
- Around line 90-97: The CSS rule for the pseudo-element
.ap-site-editor__dirty-indicator::before uses the keyword "currentColor" with
mixed-case; update the background property to use the lowercase keyword
"currentcolor" to satisfy Stylelint's casing rule and normalize CSS keyword
casing.
- Around line 61-71: The .ap-site-editor__sr-only utility uses the deprecated
clip property; update the rule in the CSS for .ap-site-editor__sr-only to remove
the clip declaration and replace it with a modern equivalent such as clip-path:
inset(50%) (and keep the existing position/size/overflow/white-space/border
rules) so the element remains visually hidden but accessible; locate the
.ap-site-editor__sr-only selector in the diff and swap the clip declaration for
clip-path: inset(50%) (or another suitable clip-path) to satisfy the lint rule.

In `@resources/js/visual-editor/site-editor/fallback-chain.ts`:
- Around line 67-121: The getTemplateKindOptions function returns the list of
template kinds but omits the "custom" kind referenced in the header/docs; update
getTemplateKindOptions (and the TemplateKindOption entries it produces) to
include a { slug: 'custom', label: 'Custom', description: 'User-defined custom
template.' } entry (or alternatively update the header text if you intend to
remove support) so the create-new picker contract matches the documentation and
the create dialog can explicitly select the custom-template flow.

In `@resources/js/visual-editor/site-editor/site-editor-app.tsx`:
- Around line 237-243: The useEffect dependency array includes an unnecessary
dependency: remove activeSection.id and leave only isD2Section in the dependency
array of the effect that resets entity state; locate the effect using useEffect,
isD2Section, setEntityState and IDLE_ENTITY_STATE and change its dependencies to
[isD2Section] (or, if you actually intend to reset when switching between D2
sections, modify the effect condition to compare previous and current
activeSection.id instead of relying solely on isD2Section).

In `@resources/js/visual-editor/site-editor/slug.ts`:
- Around line 10-12: The normalizeSlugInput function produces leading/trailing
dashes for inputs with surrounding spaces; update normalizeSlugInput to trim the
input first (call .trim()) before lowercasing and collapsing whitespace into
hyphens so "  Foo  " becomes "foo" and matches backend normalization; modify the
implementation referenced as normalizeSlugInput(value: string) to apply trim()
prior to toLowerCase() and .replace(/\s+/g, '-').

In `@resources/js/visual-editor/site-editor/template-parts-section.tsx`:
- Around line 78-87: The renderRow callback is rendering the raw machine slug
(entity.area) instead of the localized label; update renderRow in
template-parts-section.tsx to look up the human label via getTemplatePartAreas()
(e.g., const areas = getTemplatePartAreas()), render areas[entity.area] (or
areas[entity.area]?.label) and fall back to entity.area if missing, so the span
with data-testid={`ap-site-editor-template-part-area-${entity.id}`} shows the
translated area name rather than the raw slug; ensure getTemplatePartAreas is
imported where renderRow is defined.

In `@resources/js/visual-editor/site-editor/templates-section.tsx`:
- Around line 47-60: The template chip list currently only filters by
publication status; update buildTemplateChips to include chips for template
source/kind so users can filter Theme and Custom templates (e.g., add entries
with id 'theme' and 'custom', labels like __('Theme', TEXT_DOMAIN) and
__('Custom', TEXT_DOMAIN), and filters such as { kind: 'theme' } and { kind:
'custom' } or the appropriate property used by your data model), ensuring the
new FilterChip objects are returned alongside existing 'all', 'publish', and
'draft' chips so the navigator can show only theme or custom templates.
- Around line 67-75: renderRow currently only shows slug, source and status;
update the renderRow (EntityRecord<'template'>) to also render the template
fallback-chain breadcrumbs (use entity.fallbackChain or entity.fallbacks—render
each ancestor as a breadcrumb element, separated by chevrons) and add a "Used by
N" affordance showing the usage count (use entity.usageCount or call the
navigator/getter that returns usage for this template) as a clickable element
that opens the navigator/usage view for that template (call the existing
navigator/openTemplateUsage or navigator.showUsage with entity.id). Ensure
accessibility and keep existing TEXT_DOMAIN i18n calls for the new link text.
- Around line 256-259: buildPayload currently returns null when activeSlug is
empty which causes the submit handler to silently no-op; update buildPayload
(and the submit handler that consumes it) so that when activeKind === 'custom'
and the normalized activeSlug is blank you set a visible validation error on the
slug field (e.g. call the existing form error/validation setter used in this
component) and then return null/abort, or alternatively have the submit handler
detect a null payload and call the same form error setter to surface feedback to
the user; ensure you apply the same change for the other buildPayload call site
that handles custom templates.

In `@resources/js/visual-editor/site-editor/use-entity-editor.ts`:
- Around line 183-186: The fallback error string used when building the
`message` variable in use-entity-editor (where the code checks `error instanceof
SiteEditorApiError`) is hardcoded and must be localized; replace the hardcoded
`'Failed to load entity.'` with a call to the i18n helper (e.g. `__('Failed to
load entity.')`) so it matches other modules, and make the same change for the
similar fallback error around the later fallback near line ~280 in this file;
ensure you import/use the same `__` function used in `use-entity-list.ts` and
`create-entity-dialog.tsx` if not already imported.

---

Nitpick comments:
In `@resources/js/visual-editor/site-editor/entity-browser.tsx`:
- Around line 278-289: The computation of hasActive is repeated inside the
items.map loop; hoist the hasActive calculation above the map to compute it once
(use the same check: items.some(candidate => String(candidate.id) ===
activeEntityId)), then inside the map keep using hasActive to derive isTabStop
(alongside activeEntityId, index, isActive) and leave extractTitle(entity) and
the rest unchanged; update the block that currently declares hasActive within
the map to remove the per-iteration some() call.

In `@resources/js/visual-editor/site-editor/entity-editor-canvas.tsx`:
- Around line 45-62: The blocks prop on EntityEditorCanvasProps is currently
typed as readonly unknown[] which defeats type safety; change its type to
BlockInstance[] (and readonly where appropriate) so the signature in
EntityEditorCanvasProps aligns with the BlockEditorProvider and the blocks
produced by use-entity-editor.ts; update the interface property `blocks` and any
related callbacks (`onChange`, `onInput`) to accept BlockInstance[] to restore
static type checking and prevent mismatches.

In `@resources/js/visual-editor/site-editor/entity-editor.tsx`:
- Around line 233-253: The local function handlePatch is being recreated inside
the useMemo for documentPanel causing a new function identity each memo and
likely unnecessary re-renders of child panels; move handlePatch out of the
useMemo and wrap it in a stable useCallback that calls patch (e.g., const
handlePatch = useCallback((overrides: UpdatePayload) => patch(overrides),
[patch])), then pass that handlePatch into the TemplateDocumentPanel and
TemplatePartDocumentPanel and update the documentPanel hook dependencies to
include handlePatch if you keep it in the deps list.

In `@resources/js/visual-editor/site-editor/site-editor-app.tsx`:
- Around line 86-151: The ensureEditorBoot() invocation is a render-time side
effect; instead, remove the direct call from the component render and invoke
ensureEditorBoot() inside a React useEffect with an empty dependency array so it
runs once after mount (keep the ensureEditorBoot function and its editorBooted
flag unchanged for idempotency). Add the useEffect import from React if missing
and place the effect where the component hooks live; do not move the boot logic
out of ensureEditorBoot itself, only change the call site to useEffect. Ensure
the change preserves HMR behavior (the editorBooted guard remains).

In `@resources/js/visual-editor/site-editor/use-entity-editor.ts`:
- Around line 97-108: The hydrateBlocks function currently casts content.blocks
to BlockInstance[] without validation; update hydrateBlocks to
defensive-validate and normalize that array before returning: ensure
content.blocks is an array and each item has required keys (e.g., name,
attributes, innerBlocks) and types, filter out or fill missing fields with safe
defaults, and if validation fails for any element fallback to a safe path (e.g.,
re-serialize content.blocks and run parse(...) on the serialized string or
return an empty array) so Gutenberg never receives malformed BlockInstance
objects. Locate hydrateBlocks and implement the validation/normalization logic
around the return of content.blocks as BlockInstance[] and use parse(...) as the
fallback when elements are invalid.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@resources/js/visual-editor/site-editor/site-editor-app.tsx`:
- Around line 132-134: The guard that calls registerCoreBlocks() should check
for specific core block registration rather than an empty registry; replace the
current getBlockTypes().length === 0 check with a presence check for required
core blocks (for example use getBlockType('core/paragraph') or search
getBlockTypes() for 'core/paragraph' and any other essential names) and call
registerCoreBlocks() if any required core block is missing. Locate the
conditional around getBlockTypes() and update it to detect missing core blocks
(e.g., missing result from getBlockType('core/paragraph') or absent names in
getBlockTypes()), then invoke registerCoreBlocks() when those core blocks are
not present.

In `@resources/js/visual-editor/site-editor/template-parts-section.tsx`:
- Around line 138-141: The panel currently only displays the slug as read-only;
update the TemplatePartDocumentPanel (using the TemplatePartDocumentPanelProps
and the onPatch callback) to render an editable slug input (or inline text
field) alongside existing title/area controls and call onPatch({ slug: newSlug
}) when the user changes it; ensure you preserve null-checks on entity:
TemplatePartRecord, keep validation/sanitization similar to title handling, and
fall back to the existing read-only code display when entity is null or the slug
is invalid.

In `@resources/js/visual-editor/site-editor/templates-section.tsx`:
- Around line 110-113: The template document panel currently renders the slug as
read-only even though TemplateDocumentPanelProps and onPatch support editing it;
update the slug field in the TemplateDocumentPanel component (using
entity/TemplateRecord for initial value) to be an editable input in the
inspector and wire its onChange to call onPatch({ slug: newValue }) so renames
propagate; do the same change for the other occurrence that renders slug (the
similar inspector block around the other slug rendering) to ensure both places
allow editing.

In `@resources/js/visual-editor/site-editor/use-entity-editor.ts`:
- Around line 268-275: The save path currently calls hydrateFromRecord(updated)
unconditionally, allowing a stale save response for entity A to overwrite the
editor when the user has navigated to entity B; add the same out-of-order
protection used in the load path (requestCounterRef or an equivalent
saveRequestCounterRef / currentEntityIdRef) to the save flow around updateEntity
and hydrateFromRecord so you only call hydrateFromRecord(updated) when the
response corresponds to the most recent save/request for the currently open
entity (e.g., increment a counter before calling updateEntity and check the
counter or that entityId still matches before hydrating and setting save
status/lastSavedAt).
- Around line 230-233: The patch function only writes overrides into
pendingPatch, so the rendered inputs still read from the original entity; fix by
exposing a merged draft entity that combines entity and pendingPatch (or
applying the overrides into entity) before returning from useEntityEditor:
compute a draftEntity (e.g., via useMemo) that spreads the current entity and
pendingPatch (respecting UpdatePayload fields like title.rendered, description,
area) and ensure inspector panels bind to draftEntity instead of raw entity;
keep patch (useCallback) updating setPendingPatch as-is but make the hook return
or expose the merged draftEntity so edits immediately reflect in the UI.

---

Duplicate comments:
In `@resources/js/visual-editor/site-editor/templates-section.tsx`:
- Around line 47-60: buildTemplateChips currently only returns publication-state
chips and must include navigator chips for Theme and Custom; update the
buildTemplateChips function to add two new chips (e.g. id: 'theme', label:
__('Theme', TEXT_DOMAIN), filter: { source: 'theme' } and id: 'custom', label:
__('Custom', TEXT_DOMAIN), filter: { source: 'custom' }) so consumers can filter
by template origin; keep the existing 'all', 'publish', 'draft' chips, preserve
the readonly FilterChip[] return type, and ensure labels use the TEXT_DOMAIN
translation helper.
- Around line 67-75: renderRow currently only shows slug/source/status; update
it to also render the template's fallback chain and its usage count so each row
shows routing context and impact. Inside renderRow (EntityRecord<'template'>),
read the fallback list (e.g., entity.fallbackChain or entity.fallbacks) and
render as breadcrumb text (joined with → or similar) and read the usage metric
(e.g., entity.usedBy or entity.usageCount) and render "Used by N" with proper
pluralization; ensure the EntityRecord fields you use are available and add them
to the component props/state if necessary, and update the useCallback dependency
array to include any external values you reference.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@resources/js/visual-editor/site-editor/use-entity-editor.ts`:
- Around line 151-164: When handling the entityId === null branch in the
use-entity-editor hook, increment/bump the requestCounterRef to invalidate any
in-flight load/save responses so older async callbacks cannot pass the
stale-request check; update the requestCounterRef (e.g.,
requestCounterRef.current++) inside the same block where you clear state
(setEntity, setBlocksState, setPendingPatch, etc.) so outstanding promises are
ignored after navigation/close.

---

Nitpick comments:
In `@resources/js/visual-editor/site-editor/__tests__/site-editor-app.test.tsx`:
- Around line 212-232: Add a sibling test that mirrors the templates mounting
check to cover the Template Parts entrypoint: render the app with renderApp(),
then either assert directly that
screen.getByTestId('ap-site-editor-stub-template-parts-browser') is in the
document (like the templates test using 'ap-site-editor-stub-templates-browser')
or simulate navigation by clicking
screen.getByTestId('ap-site-editor-navigator-template-parts') and then assert
the section outlet
screen.getByTestId('ap-site-editor-section-outlet-template-parts') is present
and contains the expected fallback text; place this new assertion/test next to
the existing "mounts the D2 templates browser inside the navigator" test so the
Template Parts wiring is covered.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@resources/js/visual-editor/site-editor/use-entity-editor.ts`:
- Around line 317-323: The current code snapshots requestCounterRef.current so
concurrent saves for the same entity can get the same requestId; instead
reserve/allocate a new unique request id when starting a save by incrementing
requestCounterRef.current (or calling an allocator) and store that incremented
value in requestId, then keep using isStale() to compare
requestCounterRef.current !== requestId; update the save/start logic around
requestCounterRef and isStale so each save gets a unique requestId and late
responses are rejected.

---

Duplicate comments:
In `@resources/js/visual-editor/site-editor/use-entity-editor.ts`:
- Around line 171-175: When starting a new load (the branch that increments
requestId via requestCounterRef.current and calls setLoadStatus('loading') /
setLoadErrorMessage(null)), also reset the editor's working copy state so
remnants of the previous entity can't be saved to the new entity: clear blocks
(e.g. setBlocks([]) or equivalent), clear pendingPatch (setPendingPatch(null)),
clear the dirty flag (setIsDirty(false)), and clear any save metadata
(lastSavedAt/saveError/saveInProgress refs) so save() cannot PUT old draft to
the new entityId; do this in the same place (not only in the entityId === null
branch) before issuing the fetch.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@resources/js/visual-editor/site-editor/use-entity-editor.ts`:
- Around line 173-175: When starting a new entity load you only reset
load-specific state; also reset all editor/save metadata so state from entity A
doesn't leak into entity B: alongside setLoadStatus('loading') and
setLoadErrorMessage(null) call the corresponding save/editor reset setters (e.g.
setSaveStatus('idle' or null), setSaveErrorMessage(null), setLastSavedAt(null))
and clear any dirty/validation state via the editor dirty/validation setters
(e.g. setIsDirty(false), setValidationErrors([]) or resetEditorValidation).
Place these resets in the same branch that runs when initiating a new fetch so
they always run when switching entities and before handling load failures.